<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.

-->

<HTML>
  <HEAD>
    <TITLE>Chainsaw Tool</TITLE>
  </head>
    
  <BODY>

    <P>Chainsaw is a GUI log viewer and filter for the log4j
package. By default it listens for <a
href="../spi/LoggingEvent.html">LoggingEvent</A> objects sent using
the <A href="../net/SocketAppender.html">SocketAppender</A> and
displays them in a table. The events can be filtered based on:</P>

    <UL>
      <LI>Level </li>

      <LI>Thread name</li>

      <LI>Logger</li>
      <LI>Message</li>

      <LI>NDC</LI>
    </UL>

    <P>All the details for each event can be displayed by selecting
      the event in the table.</P> 

    <P>Chainsaw also supports loading a events logged to a file using
      the <A href="../xml/XMLLayout.html">XMLLayout</A> format. This
      is great for analysing log files, and means you do not need to
      keep Chainsaw running continously. It is easy to add support
      for loading events from other sources like JDBC.</P> 

    <P>A picture is worth a thousand words: </P>

    <P align=center><A
      href="doc-files/screen_01.png"><IMG
      height="50%" alt="Screen shot of chainsaw"
      src="doc-files/screen_01.png"
      width="50%"></A>.</P> 

    <P>Finally, why is it called chainsaw?
      Because it cuts your log (file) down to size. :-)
    </P>


    <H2>Requirements</H2> 

    <P>Chainsaw is based on the Swing API which requires JDK 1.2 or later.</P>


    <H2>Running chainsaw</H2>

    <H3>Setup</H3>
    <P>You need to include the <code>log4j.jar</code> in the classpath.

    <H3>Usage</H3>

    <P>The command line usage is:</P>

    <PRE>  java -D&lt;property&gt;=&lt;value&gt; org.apache.log4j.chainsaw.Main </PRE>

    <P>The default behaviour of chainsaw can be changed by setting system properties 
      using the <CODE>-D&lt;property&gt;=&lt;value&gt;</CODE> arguments to java. The 
      following table describes what properties can be set:</P>

    <TABLE cellSpacing=0 cellPadding=2 border=1>

      <TR>
	<TD vAlign=top><B>Property</B></TD>
	<TD vAlign=top><B>Description</B></TD></TR>
      <TR>
	<TD vAlign=top>chainsaw.port</TD>
	<TD vAlign=top>Indicates which port to listen for connections on. Defaults 
	  to <SPAN class=default>"4445"</SPAN>.
	</TD>
      </TR>
    </TBODY>
    </TABLE>

    <H2>Configuring Log4J</H2>

    <P>You will need to configure log4j to send logging events to
      Chainsaw.  Here is a sample <CODE>log4j.properties</CODE> file
      for sending logging events to Chainsaw.</P>

<PRE>
log4j.rootLogger=DEBUG, CHAINSAW_CLIENT

log4j.appender.CHAINSAW_CLIENT=org.apache.log4j.net.SocketAppender
log4j.appender.CHAINSAW_CLIENT.RemoteHost=localhost
log4j.appender.CHAINSAW_CLIENT.Port=4445
log4j.appender.CHAINSAW_CLIENT.LocationInfo=true
</PRE>



  </body>
</html>